Skip to content

Render web-components reference in .md exports, and add check-md-exports audit script - #603

Merged
hey-august merged 5 commits into
mainfrom
august-20260811-llms-params
Aug 19, 2026
Merged

Render web-components reference in .md exports, and add check-md-exports audit script#603
hey-august merged 5 commits into
mainfrom
august-20260811-llms-params

Conversation

@hey-august

Copy link
Copy Markdown
Collaborator

Description

Fixes

  • Rename fern/products/browser-sdk/pages/v4/web-components/*.md.mdx (27 files) and update v4.yml nav paths. These pages use <ParamField>/<CardGroup>, which Fern's .md-export path only compiles in .mdx files — every page in this section was exporting raw JSX to AI consumers while rendering fine as HTML. Verified on the preview: the exports now render every term properly.
  • Add the MDX-required blank lines inside <Accordion> blocks in 5 v4 guides (house-style normalization per documentation-style.md; note the authentication guide's export corruption turned out to be a separate Fern exporter bug — fence imbalance in <EndpointRequestSnippet> output — reported upstream, not fixable from our MDX).
  • Replace an authored &#xA; entity with a period in sw-audio-level's methods table.

New tooling:

  • scripts/check-md-exports.js (yarn check-md-exports): audits the llms.txt tree + all .md exports for structural breakage. Tiered checks (error/warn/info), --cross-check mode verifying ParamField terms from sources against deployed exports (with --source-ref origin/main to read sources from the ref the site was built from, eliminating branch-drift noise), --base-url for previews, markdown/JSON reports, CI-ready exit codes. Zero dependencies, mirrors check-links.js conventions.
  • scripts/check-md-exports.test.js (yarn test:scripts, 18 fixture tests on node:test): locks in the detection heuristics — the .md exports strip defined terms — llms.txt corpus is structurally broken #525 regression shape must trip, the legitimate older page styles must not, and the cross-check URL-mapping rules are pinned.
  • scripts/README.md: documents all repo scripts, with a usage guide for the new audit.

Verification:

  • fern check ✓; fern docs md check ✓ (2,806 MDX files valid on the rebased base); yarn test:scripts 18/18 ✓
  • Full-corpus run against production: 3,156 pages, 34 errors, all triaged
  • Preview run (--base-url <preview>/docs --product browser-sdk, 664 pages): 34 → 2 errors; both remaining are the upstream Fern snippet-fence bug
  • --source-ref origin/main --product swml: 1,469 ParamField terms across 74 sources, zero missing from deployed exports (the 3 findings from the working-tree run were confirmed as branch drift, which this mode eliminates)

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Code cleanup / refactor

Related Issues

Closes #525.

Testing

  • Added/updated unit tests
  • Tested manually
  • Tested with live SignalWire credentials (if applicable)

Checklist

  • I have read the CONTRIBUTING guidelines
  • My code follows the project's style guidelines
  • I have added tests for my changes (if applicable)
  • I have updated documentation (if applicable)
  • All existing tests pass

Additional Notes

@github-actions

github-actions Bot commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

@Devon-White
Devon-White self-requested a review August 19, 2026 14:13
@hey-august
hey-august merged commit 41dbbcc into main Aug 19, 2026
2 checks passed
@hey-august
hey-august deleted the august-20260811-llms-params branch August 19, 2026 15:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

.md exports strip defined terms — llms.txt corpus is structurally broken

2 participants